feat(devx): a docs gate binds each CLI transcript in content/docs to the registry it quotes, so a derived count cannot drift silently - #15651

Fixes #15373

A written number that nothing derives and nothing compares. content/docs teaches with pasted CLI output, and some of those lines quote a value the CLI computes from a live registry at runtime:

packages/cli/src/commands/validate.ts:245
  const registered = authoringRulesFor('validate');
  printStep(`Running author-time rules (${registered.length})...`);

The page wrote it as a literal, so it drifted on every rule added, silently. PR #15369 corrected the four stale numbers; this is the mechanism half.

1. How a transcript block says what it is a transcript OF — measured, not chosen

Both directions in the card had to answer this first. It was answered by compiling every candidate form through the real pipeline — mdxPreset({}) from fumadocs-core/content/mdx/preset-bundler, which is what defineConfig in apps/docs/source.config.ts resolves to (fumadocs-mdx 15.2.3 / fumadocs-core 16.14.4 / @mdx-js/mdx 3.1.1), over the exact transcript body these pages carry:

and two equalities on the same pipeline:

bare ``` vs ```text                     IDENTICAL compiled output
```text vs ```text + transcript meta    IDENTICAL compiled output

Chosen: fence meta on a fence that already names a language — ```text transcript=os-validate.

Then the same measurement on the four real pages, before (origin/main) vs after (this branch), whole file each:

content/docs/ui/react-pages.mdx                    before COMPILES: true  after COMPILES: true  compiled output identical: true  declaration present in output: false
content/docs/getting-started/build-with-claude-code.mdx  before: true  after: true  identical: true  present in output: false
content/docs/deployment/validating-metadata.mdx    before: true  after: true  identical: true  present in output: false
content/docs/deployment/cli.mdx                    before: true  after: true  identical: true  present in output: false

The declaration is free at both ends: byte-identical compiled output, and the meta never reaches it.

Two consequences worth stating, because both read like the obvious choice:

• The HTML-comment form does not exist in this corpus. MDX rejects HTML comments outright, at parse time, on every page. Measured rather than assumed.
• Result B is why the gate ships a no-language finding. A transcript= token in first position is read by shiki as the language name and breaks the docs build. That is the one way to write this declaration that turns a documentation-accuracy gate into an outage, so the gate refuses it where the failure is a line number instead of a red next build.

2. Why the kind is per COMMAND

The obvious design is one kind, os-validate. It is wrong on this very corpus: two of the four sites are os validate output and deployment/cli.mdx (under ◆ Compile) is os build output. Measured on d30ccb9bd against the built registry:

authoringRulesFor('validate').length   42
authoringRulesFor('build').length      42
authoringRulesFor('lint').length       39

Two agree today and the third already disagrees, so a single kind would pin an os lint transcript to a number that is wrong right now, and one rule scoped commands: ['validate'] would split the other two. The vocabulary stays tiny: the kinds ARE the registry's own AuthoringCommand union, one row each; a second quoted VALUE is a row in TOKENS, not a new kind.

3. Why not check:corpus-claim-drift — evaluated against its model

Its header is the authority. It is a shrink-only lexical co-occurrence ratchet: does an operator's spelling appear within an N-line window of phrasing naming a semantic the platform does not implement, with a per-file baseline budget. Every part of that model is words near other words.

What is pinned here is an equality between a decimal literal on a page and an integer a module exports at runtime. There is no phrase to co-occur with, no window to widen, and a baseline row would be exactly wrong — a budget for a count that is simply either right or wrong. Folding in would have meant a second, numeric model inside a lexical gate, keyed on a registry import that gate deliberately does not have (it is dependency-free by design). Two mechanisms, one corpus.

4. Why COMPARE and not STAMP

check:docs-image-tag stamps, and #15332 was ruled to stamp, and both are right for what they carry: a single generated token whose only true value is the one the release process just produced. A transcript is not that — it is a hand-authored teaching artifact, elided and annotated, and a stamper would have to own the whole block to own one number inside it. Rewriting prose into a customer-facing page from a script is a much larger claim than checking one integer inside it, and it removes the author's ability to elide. So: compare, name the page and line, let a human type the digit.

5. Where the step lives, and why NOT next to the other docs gates

The gate derives the number the way the CLI does — importing the BUILT @objectstack/lint through that package's own exports/main — so it needs a dist/. Measured on the workflows:

• lint.yml's Lint & Repo Gates, which hosts every other docs gate, runs pnpm install and never builds (grepped: no build step anywhere in that job). Placed there the gate would exit 3 on every CI run forever — a gate that never measures.
• ci.yml's Build Core builds and hosts check:dual-build-cjs-loads for exactly this reason, but it is gated on the core paths filter, which does not include content/** — so it would skip the docs-only PRs that ADD a stale transcript.
• lint.yml's Type Check · workspace has no paths filter, sits behind the required TypeScript Type Check context, and already runs turbo run build --filter='./packages/*', which includes packages/lint.

So the step sits in that lane, immediately after Build workspace packages. It adds no build and no CI minutes. With no dist/ it exits 3 (PREREQUISITE NOT MET), never 1 and never a silent 0.

Scope boundary: content/docs/** only. docs/audits/** carries the same lines with 41 in them and is deliberately out of population — a dated audit record is a historical reading, and correcting it would be falsifying it.

6. Ablations — both directions, each mutation confirmed on disk, each restore confirmed on disk

Run from the committed implementation (8aecfb84b), with an EXIT INT TERM trap holding absolute paths, hashes compared against the HEAD blob on both legs. No rebuild leg is needed: the mutated subject is the .mdx page read straight from disk, not a dist/ artifact.

ABLATION 1 — a printed count drifts (42 -> 41), content/docs/ui/react-pages.mdx
  pre-mutation blob == HEAD blob : 69e29b8c273a9e3d5b551dd46c2d57a388b92cc1 == 69e29b8c273a9e3d5b551dd46c2d57a388b92cc1
  grep count of injected '(41)' : 1     grep count of removed '(42)' : 0
  post-mutation blob d886ddd254dda246ae735cdb012f6912a622112f differs from HEAD: yes
  EXIT=1
    content/docs/ui/react-pages.mdx:380  [stale]
      author-time rules (41)
      -> prints 41, and the author-time rule count for `validate` derives 42 today
  restore: git diff HEAD -> 0 changed path(s); blob back to 69e29b8c…: yes

ABLATION 2 — a declaration is removed, content/docs/deployment/cli.mdx
  grep count of removed declaration : 0   (bare fences after mutation: 57)
  post-mutation blob differs from HEAD: yes
  EXIT=1
    content/docs/deployment/cli.mdx:456  [undeclared]
      author-time rules (42)
      -> quotes the author-time rule count but declares no transcript kind, so nothing compares it
  restore: blob back to 9e8c1af4…: yes

ABLATION 3 — the built registry is absent (packages/lint/dist moved aside)
  dist present after mutation? no
  EXIT=3
    check-docs-transcript-drift: PREREQUISITE NOT MET — … packages/lint/dist/index.js does not exist
    ⛔ This is NOT a pass and NOT a finding: nothing was measured.
  restore: dist present again: yes

CONTROL — restored tree
  EXIT=0  ✓ 4 declared transcript value(s) across 405 page(s) … equal what the registry derives today
  git status: empty

And the corpus itself was the fourth reading: before the four declarations were added, the gate reddened on all four sites with [undeclared], which is what says the ratchet is not vacuous on the live tree.

7. Derivation before / after

node scripts/pm/dispatch-gates.mjs --commands <path>, on origin/main (d30ccb9) and on this branch (8aecfb8):

Both sides of the equality this gate pins now derive it.

8. Cost

• CI minutes: zero added. The step runs in a lane that already builds; the gate itself is one directory walk of 405 .mdx pages plus one dynamic import.
• Gate wall time, measured locally on a shared box: check:docs-transcript-drift (self-test + production run) ~1.6 s total, of which the production run is ~0.4 s. The self-test spawns three child processes for its program-level battery.
• Open PRs whose change set newly derives it: any PR touching content/docs/** or packages/lint/**. On this tree that is the same population check:doc-anchors and check:docs-single-h1 already carry, so no PR gains a gate family it did not already have several of.

9. Verification

Exit codes captured before any pipe; the verdict lines are the gates' own.

Not measured, by name, with why:

One derived gate reddened and it is not this diff: pnpm check:docs-audit-scope fails affected-docs.mjs --self-test on this container. Root-caused rather than waved off — the trigger is packages/spec/.examples-build/, a gitignored scratch tree that check:skill-examples leaves behind; hold that directory out and the gate is green (✓ docs-accuracy-audit scope is in sync with content/docs/: 190 hand-written doc(s)). Two controls: a pristine worktree at this exact commit passes ✓ affected-docs self-test: 568 cases pass., and so does the same worktree after pnpm install. That is already filed as #15446 (and #15328 is the neighbouring reading); the hot file it names is not touched here.

Changeset

None — scripts/**, a workflow step and docs declarations publish nothing from any package. skip-changeset applied.

🤖 Generated with Claude Code

https://claude.ai/code/session_012zGPuVVX3deAx9LdjK8jCk

Generated by Claude Code